home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / dde / _pc / h / alarm < prev    next >
Text File  |  1992-02-09  |  5KB  |  142 lines
  1. (*
  2.  * Title:    alarm.h
  3.  * Purpose:  alarm facilities for wimp programs, using non-busy waiting
  4.  *
  5.  *)
  6.  
  7. #ifndef __alarm_h
  8. #define __alarm_h
  9.  
  10. type alarm_handler = ^procedure handler(called_at : integer;
  11.                                         handle : pointer);
  12.  
  13.  
  14. (* ----------------------------- alarm_init --------------------------------
  15.  * Description:   Initialise the alarm system. 
  16.  * 
  17.  * Parameters:    void
  18.  * Returns:       void.
  19.  * Other Info:    If this call is made more than once, then any pending
  20.  *                alarms are cancelled. 
  21.  *
  22.  *)
  23. procedure alarm_init; extern;
  24.  
  25.  
  26. (* ----------------------------- alarm_timenow -----------------------------
  27.  * Description:   Reports the current monotonic time.
  28.  * 
  29.  * Parameters:    void
  30.  * Returns:       the current monotonic time.
  31.  * Other Info:    none.
  32.  *
  33.  *)
  34. procedure alarm_timenow; extern;
  35.  
  36.  
  37. (* --------------------------- alarm_timedifference ------------------------
  38.  * Description:   Returns difference between two times.
  39.  *
  40.  * Parameters:    int t1 -- the earlier time
  41.  *                int t2 -- the later time
  42.  * Returns:       difference between t1 and t2.
  43.  * Other Info:    Times are as in SWI OS_ReadMonotonicTime. Deals with wrap
  44.  *                round of timer.
  45.  *
  46.  *)
  47. function alarm_timedifference(t1, t2 : integer) : integer; extern;
  48.  
  49.  
  50. (* ------------------------------ alarm_set --------------------------------
  51.  * Description:   Set an alarm at the given time.
  52.  *
  53.  * Parameters:    int at -- time at which alarm should occur
  54.  *                alarm_handler proc -- function to be called at alarm time
  55.  *                void *handle -- caller-supplied handle to be passed to 
  56.  *                                function
  57.  * Returns:       void.
  58.  * Other Info:    The supplied function is called before passing the event 
  59.  *                on to any idle event claimer windows. 
  60.  *                "at" is in terms of the monotonic centi-second timer.
  61.  *                The supplied function is passed the time at which it was
  62.  *                called. If you have enabled idle events, then these are
  63.  *                still returned to you; if not, RISC_OSlib uses idle events
  64.  *                internally to implement alarm calls (using non-busy
  65.  *                waiting via wimp_pollidle()).
  66.  *
  67.  *)
  68. procedure alarm_set(at : integer;
  69.                 proc : alarm_handler;
  70.                 handle : pointer); extern;
  71.  
  72.  
  73. (* ----------------------------- alarm_remove ------------------------------
  74.  * Description:   Removes an alarm which was set for a given time with a
  75.  *                given handle.
  76.  *
  77.  * Parameters:    int at -- the time at which the alarm was to be made
  78.  *                void *handle -- the given handle
  79.  * Returns:       void.
  80.  * Other Info:    If no such alarm exists this call has no effect.
  81.  *
  82.  *)
  83. procedure alarm_remove(at : integer; handle : pointer); extern;
  84.  
  85.  
  86. (* --------------------------- alarm_removeall -----------------------------
  87.  * Description:   Removes all alarms which have a given handle.
  88.  *
  89.  * Parameters:    void *handle -- the handle to search for.
  90.  * Returns:       void.
  91.  * Other Info:    none.
  92.  *
  93.  *)
  94. procedure alarm_removeall(handle : pointer); extern;
  95.  
  96.  
  97. (* ---------------------------- alarm_anypending ---------------------------
  98.  * Description:   Returns whether an alarm is pending with a given handle
  99.  *
  100.  * Parameters:    void *handle -- the handle.
  101.  * Returns:       TRUE if there are any pending alarms for this handle.
  102.  * Other Info:    none.
  103.  *
  104.  *)
  105. function alarm_anypending(handle : pointer) : boolean; extern;
  106.  
  107.  
  108. (* ----------------------------- alarm_next --------------------------------
  109.  * Description:   Informs caller whether an alarm is pending and, if so, for
  110.  *                when it is.
  111.  *
  112.  * Parameters:    int *result -- time for which alarm is pending
  113.  * Returns:       TRUE if an alarm is pending.
  114.  * Other Info:    This should be used by polling loops (if you use the
  115.  *                standard "while(TRUE) event_process();" loop then this is
  116.  *                done for you). If a polling loop finds that an alarm is set
  117.  *                it should use wimp_pollidle(with earliest time set to
  118.  *                *result of alarm_next()) rather than wimp_poll to do its
  119.  *                polling.  If you handle idle events yourself, then your
  120.  *                handler should use call_next to call the next alarm
  121.  *                function upon receiving an idle event (ie. wimp_ENULL).
  122.  *
  123.  *)
  124. function alarm_next(var result : integer) : boolean; extern;
  125.  
  126.  
  127. (* ---------------------------- alarm_callnext -----------------------------
  128.  * Description:   Calls the next alarm handler function.
  129.  *
  130.  * Parameters:    void
  131.  * Returns:       void.
  132.  * Other Info:    This is done for you if you use event_process() to do your
  133.  *                polling (or even if you sink down as far as using wimpt
  134.  *                for polling).
  135.  *
  136.  *)
  137. procedure alarm_callnext; extern;
  138.  
  139. #endif
  140.  
  141. (* end of alarm.h *)
  142.